<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<title>OpenCV: Writing documentation for OpenCV</title>
<link href="../../opencv.ico" rel="shortcut icon" type="image/x-icon" />
<link href="../../tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../jquery.js"></script>
<script type="text/javascript" src="../../dynsections.js"></script>
<script type="text/javascript" src="../../tutorial-utils.js"></script>
<link href="../../search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../search/searchdata.js"></script>
<script type="text/javascript" src="../../search/search.js"></script>
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],
    jax: ["input/TeX","output/HTML-CSS"],
});
//<![CDATA[
MathJax.Hub.Config(
{
  TeX: {
      Macros: {
          matTT: [ "\\[ \\left|\\begin{array}{ccc} #1 & #2 & #3\\\\ #4 & #5 & #6\\\\ #7 & #8 & #9 \\end{array}\\right| \\]", 9],
          fork: ["\\left\\{ \\begin{array}{l l} #1 & \\mbox{#2}\\\\ #3 & \\mbox{#4}\\\\ \\end{array} \\right.", 4],
          forkthree: ["\\left\\{ \\begin{array}{l l} #1 & \\mbox{#2}\\\\ #3 & \\mbox{#4}\\\\ #5 & \\mbox{#6}\\\\ \\end{array} \\right.", 6],
          forkfour: ["\\left\\{ \\begin{array}{l l} #1 & \\mbox{#2}\\\\ #3 & \\mbox{#4}\\\\ #5 & \\mbox{#6}\\\\ #7 & \\mbox{#8}\\\\ \\end{array} \\right.", 8],
          vecthree: ["\\begin{bmatrix} #1\\\\ #2\\\\ #3 \\end{bmatrix}", 3],
          vecthreethree: ["\\begin{bmatrix} #1 & #2 & #3\\\\ #4 & #5 & #6\\\\ #7 & #8 & #9 \\end{bmatrix}", 9],
          cameramatrix: ["#1 = \\begin{bmatrix} f_x & 0 & c_x\\\\ 0 & f_y & c_y\\\\ 0 & 0 & 1 \\end{bmatrix}", 1],
          distcoeffs: ["(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6 [, s_1, s_2, s_3, s_4[, \\tau_x, \\tau_y]]]]) \\text{ of 4, 5, 8, 12 or 14 elements}"],
          distcoeffsfisheye: ["(k_1, k_2, k_3, k_4)"],
          hdotsfor: ["\\dots", 1],
          mathbbm: ["\\mathbb{#1}", 1],
          bordermatrix: ["\\matrix{#1}", 1]
      }
  }
}
);
//]]>
</script><script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js"></script>
<link href="../../doxygen.css" rel="stylesheet" type="text/css" />
<link href="../../stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<!--#include virtual="/google-search.html"-->
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="../../opencv-logo-small.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">OpenCV
   &#160;<span id="projectnumber">4.5.2</span>
   </div>
   <div id="projectbrief">Open Source Computer Vision</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "../../search",false,'Search');
</script>
<script type="text/javascript" src="../../menudata.js"></script>
<script type="text/javascript" src="../../menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('../../',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="../../d9/df8/tutorial_root.html">OpenCV Tutorials</a></li><li class="navelem"><a class="el" href="../../df/d65/tutorial_table_of_content_introduction.html">Introduction to OpenCV</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Writing documentation for OpenCV </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#tutorial_documentation_overview">Doxygen overview </a><ul><li class="level2"><a href="#tutorial_documentation_intro">Intro </a></li>
<li class="level2"><a href="#tutorial_documentation_install">Installation </a></li>
<li class="level2"><a href="#tutorial_documentation_generate">Generate documentation </a></li>
</ul>
</li>
<li class="level1"><a href="#tutorial_documentation_quick_start">Quick start </a><ul><li class="level2"><a href="#tutorial_documentation_quick_start_1">Documentation locations </a></li>
<li class="level2"><a href="#tutorial_documentation_quick_start_2">Example </a></li>
<li class="level2"><a href="#tutorial_documentation_quick_start_3">Another example </a></li>
<li class="level2"><a href="#tutorial_documentation_quick_start_4">More details </a></li>
<li class="level2"><a href="#tutorial_documentation_quick_start_md">Supported Markdown </a><ul><li class="level3"><a href="#tutorial_documentation_md_list">lists</a></li>
<li class="level3"><a href="#tutorial_documentation_md_emph">emphasis</a></li>
<li class="level3"><a href="#tutorial_documentation_md_links">links</a></li>
<li class="level3"><a href="#tutorial_documentation_md_image">images</a></li>
<li class="level3"><a href="#tutorial_documentation_md_head">headers</a></li>
<li class="level3"><a href="#tutorial_documentation_md_headid">header id</a></li>
<li class="level3"><a href="#tutorial_documentation_md_page">page id</a></li>
<li class="level3"><a href="#tutorial_documentation_md_table">tables</a></li>
</ul>
</li>
<li class="level2"><a href="#tutorial_documentation_quick_start_5">Commonly used commands </a><ul><li class="level3"><a href="#tutorial_documentation_commands_basic">Basic commands</a></li>
<li class="level3"><a href="#tutorial_documentation_commands_include">Code inclusion commands</a></li>
<li class="level3"><a href="#tutorial_documentation_toggle_buttons_commands_include">Toggle buttons inclusion commands</a></li>
<li class="level3"><a href="#tutorial_documentation_commands_group">Grouping commands</a></li>
<li class="level3"><a href="#tutorial_documentation_commands_cite">Publication reference</a></li>
</ul>
</li>
</ul>
</li>
<li class="level1"><a href="#tutorial_documentation_steps">Step-by-step </a><ul><li class="level2"><a href="#tutorial_documentation_steps_fun">Document the function </a></li>
<li class="level2"><a href="#tutorial_documentation_steps_tutorial">Write the tutorial </a></li>
</ul>
</li>
<li class="level1"><a href="#tutorial_documentation_refs">References </a></li>
</ul>
</div>
<div class="textblock"><p><b>Prev Tutorial:</b> <a class="el" href="../../db/deb/tutorial_display_image.html">Getting Started with Images</a></p>
<p><b>Next Tutorial:</b> <a class="el" href="../../db/dfa/tutorial_transition_guide.html">Transition guide</a></p>
<table class="doxtable">
<tr>
<th align="right"></th><th align="left"></th></tr>
<tr>
<td align="right">Original author </td><td align="left">Maksim Shabunin </td></tr>
<tr>
<td align="right">Compatibility </td><td align="left">OpenCV &gt;= 3.0 </td></tr>
</table>
<h1><a class="anchor" id="tutorial_documentation_overview"></a>
Doxygen overview </h1>
<h2><a class="anchor" id="tutorial_documentation_intro"></a>
Intro </h2>
<p><a href="http://www.doxygen.nl">Doxygen</a> is documentation generation system with a lot of great features, such as:</p><ul>
<li>parse program sources to produce actual and accurate documentation</li>
<li>check documentation for errors</li>
<li>insert images and formulas</li>
<li>use markdown syntax and plain HTML for precise text formatting</li>
<li>generate documentation in many different formats</li>
</ul>
<p>OpenCV library existing documentation has been converted to doxygen format.</p>
<h2><a class="anchor" id="tutorial_documentation_install"></a>
Installation </h2>
<p>Please, check official <a href="http://doxygen.nl/download.html">download</a> and <a href="http://doxygen.nl/manual/install.html">installation</a> pages. Some linux distributions can also provide doxygen packages.</p>
<h2><a class="anchor" id="tutorial_documentation_generate"></a>
Generate documentation </h2>
<ul>
<li>Get the OpenCV sources (version 3.0 and later)</li>
<li><em>Optional:</em> get the OpenCV_contrib sources</li>
<li>Create build directory near the sources folder(s) and go into it</li>
<li>Run cmake (assuming you put sources to <em>opencv</em> folder): <div class="fragment"><div class="line">cmake -DBUILD_DOCS=ON ../opencv</div></div><!-- fragment --> Or if you get contrib sources too: <div class="fragment"><div class="line">cmake -DBUILD_DOCS=ON -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ../opencv</div></div><!-- fragment --></li>
<li>Run make: <div class="fragment"><div class="line">make doxygen</div></div><!-- fragment --></li>
<li>Open <em>doc/doxygen/html/index.html</em> file in your favorite browser</li>
<li>Test your Python code: <div class="fragment"><div class="line">make check_pylint</div></div><!-- fragment --> <dl class="section note"><dt>Note</dt><dd><a href="https://www.pylint.org/#install">Pylint</a> must be installed before running cmake to be able to test Python code. You can install using your system's package manager, or with pip: <div class="fragment"><div class="line">pip install pylint </div></div><!-- fragment --></dd></dl>
</li>
</ul>
<h1><a class="anchor" id="tutorial_documentation_quick_start"></a>
Quick start </h1>
<dl class="section note"><dt>Note</dt><dd>These instructions are specific to OpenCV library documentation, other projects can use different layout scheme and documenting agreements.</dd></dl>
<h2><a class="anchor" id="tutorial_documentation_quick_start_1"></a>
Documentation locations </h2>
<p>Whole documentation is gathered from many different places:</p>
<ul>
<li><b>source code</b> entities, like classes, functions or enumerations, should be documented in corresponding header files, right prior entity definition. See examples in next sections.</li>
<li><b>pages</b> are good place to put big pieces of text with images and code examples not directly connected with any source code entity. Pages should be located in separate files and contained in several predefined places. This tutorial is example of such page.</li>
<li><b>images</b> can be used to illustrate described things. Usually located at the same places as pages, images can be inserted to any place of the documentation.</li>
<li><b>code examples</b> show how to use the library in real applications. Each sample is self-contained file which represents one simple application. Parts of these files can be included into documentation and tutorials to demonstrate function calls and objects collaboration.</li>
<li><b>BibTeX references</b> are used to create one common bibliography. All science books, articles and proceedings served as basis for library functionality should be put in this reference list.</li>
</ul>
<p>Following scheme represents common documentation places for <em>opencv</em> repository: </p><div class="fragment"><div class="line">&lt;opencv&gt;</div><div class="line">├── doc             - doxygen config files, root page (root.markdown.in), BibTeX file (opencv.bib)</div><div class="line">│   ├── tutorials       - tutorials hierarchy (pages and images)</div><div class="line">│   └── py_tutorials    - python tutorials hierarchy (pages and images)</div><div class="line">├── modules</div><div class="line">│   └── &lt;modulename&gt;</div><div class="line">│       ├── doc         - documentation pages and images for module</div><div class="line">│       └── include     - code documentation in header files</div><div class="line">└── samples         - place for all code examples</div><div class="line">    ├── cpp</div><div class="line">    │   └── tutorial_code   - place for tutorial code examples</div><div class="line">    └── ...</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>Automatic code parser looks for all header files (<em>".h, .hpp"</em> except for <em>".inl.hpp;
.impl.hpp; _detail.hpp"</em>) in <em>include</em> folder and its subfolders. Some module-specific instructions (group definitions) and documentation should be put into <em>"include/opencv2/&lt;module-name&gt;.hpp"</em> file.</dd>
<dd>
You can put C++ template implementation and specialization to separate files (<em>".impl.hpp"</em>) ignored by doxygen.</dd>
<dd>
Files in <em>src</em> subfolder are not parsed, because documentation is intended mostly for the library users, not developers. But it still is possible to generate full documentation by customizing processed files list in cmake script (<em>doc/CMakeLists.txt</em>) and doxygen options in its configuration file (<em>doc/Doxyfile.in</em>).</dd></dl>
<p>Since version 3.0 all new modules are placed into <em>opencv_contrib</em> repository, it has slightly different layout: </p><div class="fragment"><div class="line">&lt;opencv_contrib&gt;</div><div class="line">└── modules</div><div class="line">    └── &lt;modulename&gt;</div><div class="line">        ├── doc         - documentation pages and images, BibTeX file (&lt;modulename&gt;.bib)</div><div class="line">        ├── include     - code documentation in header files</div><div class="line">        ├── samples     - place for code examples for documentation and tutorials</div><div class="line">        └── tutorials   - tutorial pages and images</div></div><!-- fragment --><h2><a class="anchor" id="tutorial_documentation_quick_start_2"></a>
Example </h2>
<p>To add documentation for functions, classes and other entities, just insert special comment prior its definition. Like this:</p>
<pre class="fragment">/** @brief Calculates the exponent of every array element.

The function exp calculates the exponent of every element of the input array:
\f[ \texttt{dst} [I] = e^{ src(I) } \f]

The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for
double-precision input. Currently, the function converts denormalized values to zeros on output.
Special values (NaN, Inf) are not handled.

@param src input array.
@param dst output array of the same size and type as src.

@sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
*/
CV_EXPORTS_W void exp(InputArray src, OutputArray dst);
</pre><p>Here you can see:</p>
<ul>
<li>special C-comment syntax denotes it is doxygen comment <pre class="fragment">/** ... */ </pre></li>
<li>command <code>brief</code> denotes following paragraph is a brief description <pre class="fragment">@brief </pre></li>
<li>empty line denotes paragraph end</li>
<li>TeX formula between <code>f[</code> and <code>f]</code> commands <pre class="fragment">\f[ ... \f] </pre></li>
<li>command <code>param</code> denotes following word is name of the parameter and following text is description of the parameter; all parameters are placed in a list <pre class="fragment">@param </pre></li>
<li>command <code>sa</code> starts "See also" paragraph containing references to some classes, methods, pages or URLs. <pre class="fragment">@sa </pre></li>
</ul>
<p>Produced reference item looks like this: </p><div class="image">
<img src="../../doxygen-2.png" alt="doxygen-2.png"/>
<div class="caption">
Reference link</div></div>
<p> The "More..." link brings you to the function documentation: </p><div class="image">
<img src="../../doxygen-1.png" alt="doxygen-1.png"/>
<div class="caption">
Function documentation</div></div>
<h2><a class="anchor" id="tutorial_documentation_quick_start_3"></a>
Another example </h2>
<p>Different comment syntax can be used for one-line short comments:</p>
<pre class="fragment">//! type of line
enum LineTypes {
    FILLED  = -1,
    LINE_4  = 4, //!&lt; 4-connected line
    LINE_8  = 8, //!&lt; 8-connected line
    LINE_AA = 16 //!&lt; antialiased line
};
</pre><p>Here:</p>
<ul>
<li>special C++-comment syntax denotes it is doxygen comment <pre class="fragment">//! </pre></li>
<li>additional symbol <code>&lt;</code> denotes this comment is located <em>after</em> documented entity <pre class="fragment">//!&lt; </pre></li>
</ul>
<p>Produced documentation block looks like this: </p><div class="image">
<img src="../../doxygen-3.png" alt="doxygen-3.png"/>
<div class="caption">
Enumeration documentation</div></div>
 <h2><a class="anchor" id="tutorial_documentation_quick_start_4"></a>
More details </h2>
<h3>Command prefix</h3>
<p>Doxygen commands starts with <code>@</code> or <code>\</code> sign: </p><pre class="fragment">@brief ...
or
\brief ...
</pre><h3>Comment syntax</h3>
<p>Doxygen comment can have different forms: </p><pre class="fragment">C-style:
/** ... */
or
/*! ... */

C++-style
//! ...
or
/// ...

Lines can start with '*':
/**
 * ...
 * ...
 */

Can be placed after documented entity:
//!&lt; ...
/**&lt; ... */
</pre><h3>Paragraph end</h3>
<p>To end paragraph, insert empty line or any command starting new paragraph: </p><pre class="fragment">@brief brief description paragraph
brief continues

new paragraph

@note new note paragraph
note paragraph continues

another paragraph
paragraph continues
</pre><h3>Naming</h3>
<p>Pages, anchors, groups and other named entities should have unique name inside the whole project. It is a good idea to prefix such identifiers with module name: </p><pre class="fragment">@page core_explanation_1 Usage explanation
@defgroup imgproc_transform Image transformations
@anchor mymodule_interesting_note
</pre><h2><a class="anchor" id="tutorial_documentation_quick_start_md"></a>
Supported Markdown </h2>
<p>Doxygen supports Markdown formatting with some extensions. Short syntax reference is described below, for details visit <a href="http://www.doxygen.nl/manual/markdown.html">Markdown support</a>.</p>
<h3><a class="anchor" id="tutorial_documentation_md_list"></a>
lists</h3>
<pre class="fragment">Bulleted:
- item1
- item2
Numbered:
1. item1
2. item2
or
-# item1
-# item2
</pre><h3><a class="anchor" id="tutorial_documentation_md_emph"></a>
emphasis</h3>
<pre class="fragment">_italic_
__bold__
use html in complex cases:
&lt;em&gt;"path/to/file"&lt;/em&gt;
</pre><h3><a class="anchor" id="tutorial_documentation_md_links"></a>
links</h3>
<pre class="fragment">explicit link:
[OpenCV main site](http://opencv.org)
automatic links:
&lt;http://opencv.org&gt;
or even:
http://opencv.org
</pre><h3><a class="anchor" id="tutorial_documentation_md_image"></a>
images</h3>
<pre class="fragment">![image caption](image path)
</pre><h3><a class="anchor" id="tutorial_documentation_md_head"></a>
headers</h3>
<pre class="fragment">Level1
======
Level2
------
### Level3
#### Level4
</pre><h3><a class="anchor" id="tutorial_documentation_md_headid"></a>
header id</h3>
<p>You can assign a unique identifier to any header to reference it from other places. </p><pre class="fragment">Header {#some_unique_identifier}
------
...
See @ref some_unique_identifier for details
</pre><h3><a class="anchor" id="tutorial_documentation_md_page"></a>
page id</h3>
<p>Each page should have additional Level1 header at the beginning with page title and identifier: </p><pre class="fragment">Writing documentation for OpenCV {#tutorial_documentation}
================================
</pre><h3><a class="anchor" id="tutorial_documentation_md_table"></a>
tables</h3>
<p>Example from doxygen documentation: </p><pre class="fragment">First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell
</pre><h2><a class="anchor" id="tutorial_documentation_quick_start_5"></a>
Commonly used commands </h2>
<p>Most often used doxygen commands are described here with short examples. For the full list of available commands and detailed description, please visit <a href="http://www.doxygen.nl/manual/commands.html">Command reference</a>.</p>
<h3><a class="anchor" id="tutorial_documentation_commands_basic"></a>
Basic commands</h3>
<ul>
<li><b>brief</b> - paragraph with brief entity description</li>
<li><p class="startli"><b>param</b> - description of function argument.</p>
<p class="startli">Multiple adjacent statements are merged into one list. If argument with this name is not found in actual function signature - doxygen warning will be produced. Function can have either <em>no</em> documented parameters, either <em>all</em> should be documented.</p>
</li>
<li><b>sa</b> - "See also" paragraph, contains references to classes, functions, pages or URLs</li>
<li><b>note</b> - visually highlighted "Note" paragraph. Multiple adjacent statements are merged into one block.</li>
<li><b>return, returns</b> - describes returned value of a function</li>
<li><b>overload</b> - adds fixed text to the function description: <em>"This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts."</em></li>
<li><b>anchor</b> - places invisible named anchor, which can be referenced by <code>ref</code> command. It can be used in pages only.</li>
<li><p class="startli"><b>ref</b> - explicit reference to a named section, page or anchor.</p>
<p class="startli">If such entity can not be found - doxygen warning will be generated. This command has an optional argument - link text.</p>
<p class="startli">Doxygen also generates some links automatically: if text contains word which can be found in documented entities - reference will be generated. This functionality can be disabled by prefixing the word with <code>%</code> symbol. </p><pre class="fragment">Explicit reference: @ref MyClass
Explicit named reference: @ref example_page "Example page"
Implicit reference: cv::abc::MyClass1 or just MyClass1
Disable implicit reference: %MyClass1</pre></li>
<li><p class="startli"><b>f</b> - formula</p>
<p class="startli">Inline formulas are bounded with <code>f$</code> command: </p><pre class="fragment">\f$ ... \f$</pre><p class="startli">Block formulas - with <code>f[</code> and <code>f]</code> commands: </p><pre class="fragment">\f[ ... \f]</pre></li>
</ul>
<h3><a class="anchor" id="tutorial_documentation_commands_include"></a>
Code inclusion commands</h3>
<p>To mark some text as a code in documentation, <em>code</em> and <em>endcode</em> commands are used. </p><pre class="fragment">@code
float val = img.at&lt;float&gt;(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
                          borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
@endcode
</pre><p>Syntax will be highlighted according to the currently parsed file type (C++ for <em>.hpp</em>, C for <em>.h</em>) or you can manually specify it in curly braces:</p>
<pre class="fragment">@code{.xml}
</pre><p>To include whole example file into documentation, <em>include</em> and <em>includelineno</em> commands are used. The file is searched in common samples locations, so you can specify just its name or short part of the path. The <em>includelineno</em> version also shows line numbers but prevents copy-pasting since the line numbers are included.</p>
<pre class="fragment">@include samples/cpp/test.cpp
</pre><p>If you want to include some parts of existing example file - use <em>snippet</em> command.</p>
<p>First, mark the needed parts of the file with special doxygen comments: </p><pre class="fragment">//! [var_init]
int a = 0;
//! [var_init]
</pre><p>Then include this snippet into documentation: </p><pre class="fragment">@snippet samples/cpp/test.cpp var_init
</pre><dl class="section note"><dt>Note</dt><dd>Currently most of such partial inclusions are made with <em>dontinclude</em> command for compatibility with the old rST documentation. But newly created samples should be included with the <em>snippet</em> command, since this method is less affected by the changes in processed file.</dd></dl>
<h3><a class="anchor" id="tutorial_documentation_toggle_buttons_commands_include"></a>
Toggle buttons inclusion commands</h3>
<p>Toggle buttons are used to display the selected configuration (e.g. programming language, OS, IDE).</p>
<p>To use the buttons in documentation, <em>add_toggle</em> and <em>end_toggle</em> commands are used.</p>
<p>The command <em>add_toggle</em> can be</p><ul>
<li>general: <em>add_toggle{Button Name}</em></li>
<li>for C++: <em>add_toggle_cpp</em></li>
<li>for Java: <em>add_toggle_java</em></li>
<li>for Python: <em>add_toggle_python</em></li>
</ul>
<p>Example: </p><pre class="fragment">@add_toggle{Button Name}

  text / code / doxygen commands

@end_toggle
</pre><p>For example using toggle buttons with text and <a class="el" href="../../d4/db1/tutorial_documentation.html#tutorial_documentation_commands_include">code</a> snippets:</p>
<pre class="fragment">### Buttons Example

@add_toggle_cpp

   Text for C++ button
   @snippet samples/cpp/tutorial_code/introduction/documentation/documentation.cpp hello_world

@end_toggle

@add_toggle_java

   Text for Java button
   @snippet samples/java/tutorial_code/introduction/documentation/Documentation.java  hello_world

@end_toggle

@add_toggle_python

   Text for Python button
   @snippet samples/python/tutorial_code/introduction/documentation/documentation.py hello_world

@end_toggle</pre><p>Result looks like this:</p>
<h3>Buttons Example</h3>
 <div class='newInnerHTML' title='cpp' style='display: none;'>C++</div><div class='toggleable_div label_cpp' style='display: none;'><p>Text for C++ button </p><div class="fragment"><div class="line">    std::cout &lt;&lt; <span class="stringliteral">&quot;Hello World!&quot;</span>;</div></div><!-- fragment -->  </div>  <div class='newInnerHTML' title='java' style='display: none;'>Java</div><div class='toggleable_div label_java' style='display: none;'><p>Text for Java button </p><div class="fragment"><div class="line">        System.out.println (<span class="stringliteral">&quot;Hello World!&quot;</span>);</div></div><!-- fragment -->  </div>  <div class='newInnerHTML' title='python' style='display: none;'>Python</div><div class='toggleable_div label_python' style='display: none;'><p>Text for Python button </p><div class="fragment"><div class="line"><a class="code" href="../../df/d57/namespacecv_1_1dnn.html#a701210a0203f2786cbfd04b2bd56da47">print</a>(<span class="stringliteral">&#39;Hello world!&#39;</span>)</div></div><!-- fragment -->  </div> <p>As you can see, the buttons are added automatically under the previous heading.</p>
<h3><a class="anchor" id="tutorial_documentation_commands_group"></a>
Grouping commands</h3>
<p>All code entities should be put into named groups representing OpenCV modules and their internal structure, thus each module should be associated with a group with the same name. Good place to define groups and subgroups is the main header file for this module: <em>"&lt;module&gt;/include/opencv2/&lt;module&gt;.hpp"</em>.</p>
<dl class="section note"><dt>Note</dt><dd>Doxygen groups are called "modules" and are shown on "Modules" page.</dd></dl>
<pre class="fragment">/**
@defgroup mymodule My great module
    optional description
@{
    @defgroup mymodule_basic Basic operations
        optional description
    @defgroup mymodule_experimental Experimental operations
        optional description
@}
*/
</pre><p>To put classes and functions into specific group, just add <code>ingroup</code> command to its documentation, or wrap the whole code block with <code>addtogroup</code> command:</p>
<pre class="fragment">/** @brief Example function
    @ingroup mymodule
*/
or
/**
@addtogroup mymodule_experimental
@{
*/
... several functions, classes or enumerations here
/**
@}
*/
</pre><h3><a class="anchor" id="tutorial_documentation_commands_cite"></a>
Publication reference</h3>
<p>Use <em>cite</em> command to insert reference to related publications listed in <a class="el" href="../../d0/de3/citelist.html">Bibliography</a> page.</p>
<p>First, add publication BibTeX record into <em>"&lt;opencv&gt;/doc/opencv.bib"</em> or <em>"&lt;opencv_contrib&gt;/modules/&lt;module&gt;/doc/&lt;module&gt;.bib"</em> file: </p><pre class="fragment">@ARTICLE{Bradski98,
    author = {Bradski, Gary R},
    title = {Computer vision face tracking for use in a perceptual user interface},
    year = {1998},
    publisher = {Citeseer}
}
</pre><dl class="section note"><dt>Note</dt><dd>Try not to add publication duplicates because it can confuse documentation readers and writers later.</dd></dl>
<p>Then make reference with <em>cite</em> command: </p><pre class="fragment">@cite Bradski98
</pre><dl class="section note"><dt>Note</dt><dd>To get BibTeX record for the publications one can use <a href="http://scholar.google.ru/">Google Scholar</a>. Once the publication have been found - follow its "Cite" link and then choose "BibTeX" option: <div class="image">
<img src="../../scholarship_cite_dialog.png" alt="scholarship_cite_dialog.png"/>
</div>
</dd></dl>
<h1><a class="anchor" id="tutorial_documentation_steps"></a>
Step-by-step </h1>
<p>Steps described in this section can be used as checklist during documentation writing. It is not necessary to do things in the same order, but some steps really depend on previous. And of course these steps are just basic guidelines, there is always a place for creativity.</p>
<h2><a class="anchor" id="tutorial_documentation_steps_fun"></a>
Document the function </h2>
<ol type="1">
<li>Add empty doxygen comment preceding function definition.</li>
<li>Add <em>brief</em> command with short description of function meaning at the beginning.</li>
<li>Add detailed description of the function.</li>
<li><em>Optional</em>: insert formulas, images and blocks of example code to illustrate complex cases</li>
<li><em>Optional</em>: describe each parameter using the <em>param</em> command.</li>
<li><em>Optional</em>: describe return value of the function using the <em>returns</em> command.</li>
<li><em>Optional</em>: add "See also" section with links to similar functions or classes</li>
<li><em>Optional</em>: add bibliographic reference if any.</li>
<li>Test your code. (Python: "make check_pylint")</li>
<li>Generate doxygen documentation and verify results.</li>
</ol>
<h2><a class="anchor" id="tutorial_documentation_steps_tutorial"></a>
Write the tutorial </h2>
<ol type="1">
<li>Formulate the idea to be illustrated in the tutorial.</li>
<li><p class="startli">Make the example application, simple enough to be understood by a beginning developer. Be laconic and write descriptive comments, don't try to avoid every possible runtime error or to make universal utility. Your goal is to illustrate the idea. And it should fit one source file!</p>
<p class="startli">If you want to insert code blocks from this file into your tutorial, mark them with special doxygen comments (see <a class="el" href="../../d4/db1/tutorial_documentation.html#tutorial_documentation_commands_include">here</a>).</p>
<p class="startli">If you want to write the tutorial in more than one programming language, use the toggle buttons for alternative comments and code (see <a class="el" href="../../d4/db1/tutorial_documentation.html#tutorial_documentation_toggle_buttons_commands_include">here</a>).</p>
</li>
<li><p class="startli">Collect results of the application work. It can be "before/after" images or some numbers representing performance or even a video.</p>
<p class="startli">Save it in appropriate format for later use in the tutorial:</p><ul>
<li>To save simple graph-like images use lossless ".png" format.</li>
<li>For photo-like images - lossy ".jpg" format.</li>
<li>Numbers will be inserted as plain text, possibly formatted as table.</li>
<li>Video should be uploaded on YouTube.</li>
</ul>
</li>
<li>Create new tutorial page (<em>".markdown"</em>-file) in corresponding location (see <a class="el" href="../../d4/db1/tutorial_documentation.html#tutorial_documentation_quick_start_1">here</a>), and place all image files near it (or in "images" subdirectory). Also put your example application file and make sure it is compiled together with the OpenCV library when <code>-DBUILD_EXAMPLES=ON</code> option is enabled on cmake step.</li>
<li>Modify your new page:<ul>
<li>Add page title and identifier, usually prefixed with <em>"tutorial_"</em> (see <a class="el" href="../../d4/db1/tutorial_documentation.html#tutorial_documentation_md_page">here</a>). You can add a link to the previous and next tutorial using the identifier <pre class="fragment">@prev_tutorial{identifier}
@next_tutorial{identifier}</pre> <dl class="section warning"><dt>Warning</dt><dd>Do <b>not</b> write the <b>hashtag (#)</b>, example: <br />
 Incorrect:<pre class="fragment">@prev_tutorial{#tutorial_documentation} </pre> Correct:<pre class="fragment">@prev_tutorial{tutorial_documentation} </pre></dd></dl>
</li>
<li>Add brief description of your idea and tutorial goals.</li>
<li>Describe your program and/or its interesting pieces.</li>
<li><p class="startli">Describe your results, insert previously added images or other results.</p>
<p class="startli">To add a youtube video, e.g. www.youtube.com/watch?v= <b>ViPN810E0SU</b>, use <em>youtube</em>{<b>Video ID</b>}: </p><pre class="fragment">@youtube{ViPN810E0SU}</pre></li>
<li>Add bibliographic references if any (see <a class="el" href="../../d4/db1/tutorial_documentation.html#tutorial_documentation_commands_cite">here</a>).</li>
</ul>
</li>
<li><p class="startli">Add newly created tutorial to the corresponding table of contents. Just find <em>"table_of_content_*.markdown"</em> file with the needed table and place new record in it similar to existing ones.</p>
<p class="startli">It is simply a list item with special <em>subpage</em> command which marks your page as a child and places it into the existing pages hierarchy. Also note the list item indent, empty lines between paragraphs and special <em>italic</em> markers.</p>
</li>
<li>Generate doxygen documentation and verify results.</li>
</ol>
<h1><a class="anchor" id="tutorial_documentation_refs"></a>
References </h1>
<ul>
<li><a href="http://www.doxygen.nl">Doxygen</a> - main Doxygen page</li>
<li><a href="http://www.doxygen.nl/manual/docblocks.html">Documenting basics</a> - how to include documentation in code</li>
<li><a href="http://www.doxygen.nl/manual/markdown.html">Markdown support</a> - supported syntax and extensions</li>
<li><a href="http://www.doxygen.nl/manual/formulas.html">Formulas support</a> - how to include formulas</li>
<li><a href="http://docs.mathjax.org/en/latest/input/tex/macros/index.html">Supported formula commands</a> - HTML formulas use MathJax script for rendering</li>
<li><a href="http://www.doxygen.nl/manual/commands.html">Command reference</a> - supported commands and their parameters </li>
</ul>
</div></div><!-- contents -->
<!-- HTML footer for doxygen 1.8.6-->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Apr 2 2021 11:36:36 for OpenCV by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="../../doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
<script type="text/javascript">
//<![CDATA[
addTutorialsButtons();
//]]>
</script>
</body>
</html>
